.TH "Slurm API" "3" "Slurm job step context functions" "April 2015" "Slurm job step context functions"

.SH "NAME"
slurm_step_ctx_create, slurm_step_ctx_create_no_alloc,
slurm_step_ctx_daemon_per_node_hack, slurm_step_ctx_get,
slurm_step_ctx_params_t_init, slurm_jobinfo_ctx_get,
slurm_spawn_kill, slurm_step_ctx_destroy \- Slurm task spawn functions

.SH "SYNTAX"
.LP
#include <slurm/slurm.h>
.LP
.LP
slurm_step_ctx \fBslurm_step_ctx_create\fR (
.br
	slurm_step_ctx_params_t *\fIstep_req\fP
.br
);
.LP
slurm_step_ctx \fBslurm_step_ctx_create_no_alloc\fR (
.br
	slurm_step_ctx_params_t *\fIstep_req\fP
.br
);
.LP
int \fBslurm_step_ctx_daemon_per_node_hack\fR (
.br
	slurm_step_ctx_t *\fIctx\fP
.br
);
.LP
int \fBslurm_step_ctx_get\fR (
.br
	slurm_step_ctx_t *\fIctx\fP,
.br
	int \fIctx_key\fP,
.br
	...
.br
);
.LP
int \fBslurm_jobinfo_ctx_get\fR (
.br
	switch_jobinfo_t \fIjobinfo\fP,
.br
	int \fIdata_type\fP,
.br
	void *\fIdata\fP
.br
);
.LP
void \fBslurm_step_ctx_params_t_init\fR (
.br
	slurm_step_ctx_params_t *\fIstep_req\fP
.br
);
.LP
int \fBslurm_spawn\fR {
.br
	slurm_step_ctx \fIctx\fP,
.br
	int *\fIfd_array\fP
.br
);
.LP
int \fBslurm_spawn_kill\fR {
.br
        slurm_step_ctx \fIctx\fP,
.br
	uint16_t \fIsignal\fP
.br
);
.LP
int \fBslurm_step_ctx_destroy\fR {
.br
	slurm_step_ctx \fIctx\fP
.br
);
.SH "ARGUMENTS"
.LP
.TP
\fIstep_req\fP
Specifies the pointer to the structure with job step request specification. See
slurm.h for full details on the data structure's contents.
.TP
\fIctx\fP
Job step context. Created by \fBslurm_step_ctx_create\fR, or
\fBslurm_step_ctx_create_no_alloc\fR used in subsequent
function calls, and destroyed by \fBslurm_step_ctx_destroy\fR.
.TP
\fIctx_key\fP
Identifies the fields in \fIctx\fP to be collected by \fBslurm_step_ctx_get\fR.
.TP
\fIdata\fP
Storage location for requested data. See \fIdata_type\fP below.
.TP
\fIdata_type\fP
Switch\-specific data requested. The interpretation of this field depends
upon the switch plugin in use.
.TP
\fIfd_array\fP
Array of socket file descriptors to be connected to the initiated tasks.
Tasks will be connected to these file descriptors in order of their
task id.
This socket will carry standard input, output and error for the task.
\fIjobinfo\fP
Switch\-specific job information as returned by \fBslurm_step_ctx_get\fR.
.TP
\fIsignal\fP
Signal to be sent to the spawned tasks.
.SH "DESCRIPTION"
.LP
\fBslurm_jobinfo_ctx_get\fR Get values from a \fIjobinfo\fR field as
returned by \fBslurm_step_ctx_get\fR. The operation of this function
is highly dependent upon the switch plugin in use.
.LP
\fBslurm_step_ctx_create\fR Create a job step context. To avoid memory
leaks call \fBslurm_step_ctx_destroy\fR when the use of this context is
finished. NOTE: this function creates a slurm job step. Call \fBslurm_spawn\fR
in a timely fashion to avoid having job step credentials time out. If
\fBslurm_spawn\fR is not used, explicitly cancel the job step.
.LP
\fBslurm_step_ctx_create_no_alloc\fR Same as above, only no
allocation is made. To avoid memory leaks call
\fBslurm_step_ctx_destroy\fR when the use of this context is finished.
.LP
\fBslurm_step_ctx_daemon_per_node_hack\fR Hack the step context to run
a single process per node, regardless of the settings selected at
slurm_step_ctx_create time.
.LP
\fBslurm_step_ctx_get\fR Get values from a job step context.
\fIctx_key\fP identifies the fields to be gathered from the job step context.
Subsequent arguments to this function are dependent upon the value
of \fIctx_key\fP. See the \fBCONTEXT KEYS\fR section for details.
.LP
\fBslurm_step_ctx_params_t_init\fR This initializes parameters in the
structure that you will pass to slurm_step_ctx_create().
.LP
\fBslurm_spawn\fR Spawn tasks based upon a job step context
and establish communications with the tasks using the socket
file descriptors specified.
Note that this function can only be called once for each job
step context.
Establish a new job step context for each set of tasks to be spawned.
.LP
\fBslurm_spawn_kill\fR Signal the tasks spawned for this context
by \fBslurm_spawn\fR.
.LP
\fBslurm_step_ctx_destroy\fR Destroy a job step context created by
\fBslurm_step_ctx_create\fR.
.SH "CONEXT KEYS"
.TP
\fBSLURM_STEP_CTX_ARGS\fR
Set the argument count and values for the executable.
Accepts two additional arguments, the first of type int and
the second of type char **.
.TP
\fBSLURM_STEP_CTX_CHDIR\fR
Have the remote process change directory to the specified location
before beginning execution. Accepts one argument of type
char * identifying the directory's pathname. By default
the remote process will execute in the same directory pathname
from which it is spawned. NOTE: This assumes that same directory
pathname exists on the other nodes.
.TP
\fBSLURM_STEP_CTX_ENV\fR
Sets the environment variable count and values for the executable.
Accepts two additional arguments, the first of type int and
the second of type char **. By default the current environment
variables are copied to started task's environment.
.TP
\fBSLURM_STEP_CTX_RESP\fR
Get the job step response message.
Accepts one additional argument of type job_step_create_response_msg_t **.
.TP
\fBSLURM_STEP_CTX_STEPID\fR
Get the step id of the created job step.
Accepts one additional argument of type uint32_t *.
.TP
\fBSLURM_STEP_CTX_TASKS\fR
Get the number of tasks per node for a given job.
Accepts one additional argument of type uint32_t **.
This argument will be set to point to an array with the
task counts of each node in an element of the array.
See \fBSLURM_STEP_CTX_TID\fR below to determine the
task ID numbers associated with each of those tasks.
.TP
\fBSLURM_STEP_CTX_TID\fR
Get the task ID numbers associated with the tasks allocated to
a specific node.
Accepts two additional arguments, the first of type int and
the second of type uint32_t **. The first argument identifies
the node number of interest (zero origin). The second argument
will be set to point to an array with the task ID numbers of
each task allocated to the node (also zero origin).
See \fBSLURM_STEP_CTX_TASKS\fR above to determine how many
tasks are associated with each node.
.SH "RETURN VALUE"
.LP
For \fB slurm_step_ctx_create\fR a context is return upon success. On error
NULL is returned and the Slurm error code is set appropriately.
.LP
For all other functions zero is returned upon success.
On error, \-1 is returned, and the Slurm error code is set appropriately.
.SH "ERRORS"
.LP
\fBEINVAL\fR Invalid argument
.LP
\fBSLURM_PROTOCOL_VERSION_ERROR\fR Protocol version has changed, re\-link your code.
.LP
\fBESLURM_INVALID_JOB_ID\fR the requested job id does not exist.
.LP
\fBESLURM_ALREADY_DONE\fR the specified job has already completed and can not be modified.
.LP
\fBESLURM_ACCESS_DENIED\fR the requesting user lacks authorization for the requested action (e.g. trying to delete or modify another user's job).
.LP
\fBESLURM_DISABLED\fR the ability to create a job step is currently disabled.
This is indicative of the job being suspended. Retry the call as desired.
.LP
\fBESLURM_INTERCONNECT_FAILURE\fR failed to configure the node interconnect.
.LP
\fBESLURM_BAD_DIST\fR task distribution specification is invalid.
.LP
\fBSLURM_PROTOCOL_SOCKET_IMPL_TIMEOUT\fR Timeout in communicating with
Slurm controller.
.SH "EXAMPLE
.LP
SEE \fBslurm_step_launch\fR(3) man page for an example of slurm_step_ctx_create
and slurm_step_launch in use together.

.SH "NOTE"
These functions are included in the libslurm library,
which must be linked to your process for use
(e.g. "cc \-lslurm myprog.c").

.SH "COPYING"
Copyright (C) 2004-2007 The Regents of the University of California.
Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
CODE\-OCEC\-09\-009. All rights reserved.
.LP
This file is part of Slurm, a resource management program.
For details, see <https://slurm.schedmd.com/>.
.LP
Slurm is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version.
.LP
Slurm is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details.
.SH "SEE ALSO"
.LP
\fBslurm_allocate_resources\fR(3), \fBslurm_job_step_create\fR(3),
\fBslurm_kill_job\fR(3),
\fBslurm_get_errno\fR(3), \fBslurm_perror\fR(3), \fBslurm_strerror\fR(3),
\fBsrun\fR(1)
